\rcube_ldap

Model class to access an LDAP address directory

Summary

Methods
Properties
Constants
get_name()
set_search_set()
get_search_set()
reset()
refresh_search()
list_records()
search()
count()
get_result()
get_record()
get_error()
close()
set_page()
set_pagesize()
set_sort_order()
validate()
insert()
insertMultiple()
update()
delete()
undelete()
delete_all()
set_group()
list_groups()
get_group()
create_group()
delete_group()
rename_group()
add_to_group()
remove_from_group()
get_record_groups()
get_col_values()
compose_display_name()
compose_list_name()
compose_search_name()
compose_contact_key()
__construct()
list_group_members()
_entry_sort_cmp()
set_debug()
dn_encode()
dn_decode()
$primary_key
$groups
$export_groups
$readonly
$searchonly
$undelete
$ready
$group_id
$list_page
$page_size
$sort_col
$sort_order
$date_cols
$coltypes
$vcard_map
ERROR_READ_ONLY
ERROR_NO_CONNECTION
ERROR_VALIDATE
ERROR_SAVING
ERROR_SEARCH
SEARCH_ALL
SEARCH_STRICT
SEARCH_PREFIX
SEARCH_GROUPS
TYPE_CONTACT
TYPE_RECIPIENT
TYPE_TRUSTED_SENDER
TYPE_DEFAULT
TYPE_WRITEABLE
TYPE_READONLY
set_error()
compare_search_value()
extended_search()
add_autovalues()
$error
$ldap
$formats
$prop
$fieldmap
$filter
$sub_filter
$result
$ldap_result
$mail_domain
$debug
N/A
_connect()
_list_group_members()
_list_group_memberurl()
_ldap2result()
_map_field()
_map_data()
_attr_name()
is_group_entry()
_fetch_groups()
get_group_entry()
get_group_member_attr()
$group_types
$base_dn
$groups_base_dn
$group_data
$group_search_cache
$cache
N/A

Constants

ERROR_READ_ONLY

ERROR_READ_ONLY = 1

ERROR_NO_CONNECTION

ERROR_NO_CONNECTION = 2

ERROR_VALIDATE

ERROR_VALIDATE = 3

ERROR_SAVING

ERROR_SAVING = 4

SEARCH_ALL

SEARCH_ALL = 0

SEARCH_STRICT

SEARCH_STRICT = 1

SEARCH_PREFIX

SEARCH_PREFIX = 2

SEARCH_GROUPS

SEARCH_GROUPS = 4

TYPE_CONTACT

TYPE_CONTACT = 0

TYPE_RECIPIENT

TYPE_RECIPIENT = 1

TYPE_TRUSTED_SENDER

TYPE_TRUSTED_SENDER = 2

TYPE_DEFAULT

TYPE_DEFAULT = 4

TYPE_WRITEABLE

TYPE_WRITEABLE = 8

TYPE_READONLY

TYPE_READONLY = 16

Properties

$primary_key

$primary_key : string

Type

string — Name of the primary key field of this addressbook. Used to search for previously retrieved IDs.

$groups

$groups : bool

Type

bool — True if the addressbook supports contact groups.

$export_groups

$export_groups : bool

Type

bool — True if the addressbook supports exporting contact groups. Requires the implementation of get_record_groups().

$readonly

$readonly : bool

Type

bool — True if the addressbook is read-only.

$searchonly

$searchonly : bool

Type

bool — True if the addressbook does not support listing all records but needs use of the search function.

$undelete

$undelete : bool

Type

bool — True if the addressbook supports restoring deleted contacts.

$ready

$ready : bool

Type

bool — True if the addressbook is ready to be used. See rcmail_action_contacts_index::$CONTACT_COLTYPES

$group_id

$group_id : null|string|int

Type

null|string|int — If set, addressbook-specific identifier of the selected group. All contact listing and contact searches will be limited to contacts that belong to this group.

$list_page

$list_page : int

Type

int — The current page of the listing. Numbering starts at 1.

$page_size

$page_size : int

Type

int — The maximum number of records shown on a page.

$sort_col

$sort_col : string

Type

string — Contact field by which to order listed records.

$sort_order

$sort_order : string

Type

string — Whether sorting of records by $sort_col is done in ascending (ASC) or descending (DESC) order.

$date_cols

$date_cols : string[]

Type

string[] — A list of record fields that contain dates.

$coltypes

$coltypes : array

Type

array — Definition of the contact fields supported by the addressbook.

$vcard_map

$vcard_map : string[]

Type

string[] — vCard additional fields mapping

$error

$error : ?array

Type

?array — Error state - hash array with the following fields: type, message

$ldap

$ldap

$formats

$formats

$prop

$prop

$fieldmap

$fieldmap

$filter

$filter

$sub_filter

$sub_filter

$result

$result

$ldap_result

$ldap_result

$mail_domain

$mail_domain

$debug

$debug

$group_types

$group_types : array

Group objectclass (lowercase) to member attribute mapping

Type

array

$base_dn

$base_dn

$groups_base_dn

$groups_base_dn

$group_data

$group_data

$group_search_cache

$group_search_cache

$cache

$cache

Methods

get_name()

get_name() : string

Returns address book name

Returns

string —

Address book name

set_search_set()

set_search_set(string  $filter) : void

Save a search string for future listings

Parameters

string $filter

Filter string

get_search_set()

get_search_set() : mixed

Getter for saved search properties

Returns

mixed —

Search properties used by this class

reset()

reset() : void

Reset all saved results and search parameters

refresh_search()

refresh_search() : mixed

Refresh saved search set after data has changed

Returns

mixed —

New search set

list_records()

list_records(array  $cols = null, int  $subset, bool  $nocount = false) : array

List the current set of contact records

Parameters

array $cols

List of cols to show

int $subset

Only return this number of records

bool $nocount

True to skip the count query (Not used)

Returns

array —

Indexed list of contact records, each a hash array

search()

search(mixed  $fields, mixed  $value, int  $mode, bool  $select = true, bool  $nocount = false, array  $required = []) : \rcube_result_set

Search contacts

Parameters

mixed $fields

The field name of array of field names to search in

mixed $value

Search value (or array of values when $fields is array)

int $mode

Matching mode. Sum of rcube_addressbook::SEARCH_*

bool $select

True if results are requested, False if count only

bool $nocount

(Not used)

array $required

List of fields that cannot be empty

Returns

\rcube_result_set —

List of contact records

count()

count() : object

Count number of available contacts in database

Returns

object —

rcube_result_set Resultset with values for 'count' and 'first'

get_result()

get_result() : object

Return the last result set

Returns

object —

rcube_result_set Current resultset or NULL if nothing selected yet

get_record()

get_record(mixed  $dn, bool  $assoc = false) : mixed

Get a specific contact record

Parameters

mixed $dn

Record identifier

bool $assoc

Return as associative array

Returns

mixed —

Hash array or rcube_result_set with all record fields

get_error()

get_error() : array

Returns the last error occurred (e.g. when updating/inserting failed)

Returns

array —

Hash array with the following fields: type, message

close()

close() : mixed

Close connection to LDAP server

Returns

mixed —

set_page()

set_page(mixed  $page) : mixed

Set internal list page

Parameters

mixed $page

Page number to list

Returns

mixed —

set_pagesize()

set_pagesize(mixed  $size) : mixed

Set internal page size

Parameters

mixed $size

Number of messages to display on one page

Returns

mixed —

set_sort_order()

set_sort_order(string  $sort_col, string  $sort_order = null) : mixed

Set internal sort settings

Parameters

string $sort_col

Sort column

string $sort_order

Sort order

Returns

mixed —

validate()

validate(array  $save_data, bool  $autofix = false) : bool

Check the given data before saving.

If input not valid, the message to display can be fetched using get_error()

Parameters

array $save_data

Associative array with data to save

bool $autofix

Try to fix/complete record automatically

Returns

bool —

True if input is valid, False if not.

insert()

insert(array  $save_cols, bool  $check = false) : mixed

Create a new contact record

Parameters

array $save_cols

Associative array with save data Keys: Field name with optional section in the form FIELD:SECTION Values: Field value. Can be either a string or an array of strings for multiple values

bool $check

True to check for duplicates first

Returns

mixed —

The created record ID on success, False on error

insertMultiple()

insertMultiple(\rcube_result_set  $recset, bool  $check = false) : array

Create new contact records for every item in the record set

Parameters

\rcube_result_set $recset

Recordset to insert

bool $check

True to check for duplicates first

Returns

array —

List of created record IDs

update()

update(mixed  $id, array  $save_cols) : bool

Update a specific contact record

Parameters

mixed $id

Record identifier

array $save_cols

Hash array with save data

Returns

bool —

True on success, False on error

delete()

delete(array  $ids, bool  $force = true) : int|bool

Mark one or more contact records as deleted

Parameters

array $ids

Record identifiers

bool $force

Remove record(s) irreversible (unsupported)

Returns

int|bool —

Number of deleted records on success, False on error

undelete()

undelete(array  $ids) : mixed

Unmark delete flag on contact record(s)

Parameters

array $ids

Record identifiers

Returns

mixed —

delete_all()

delete_all(bool  $with_groups = false) : mixed

Remove all contact records

Parameters

bool $with_groups

Delete also groups if enabled

Returns

mixed —

set_group()

set_group(mixed  $group_id) : mixed

Setter for the current group

Parameters

mixed $group_id

Group identifier

Returns

mixed —

list_groups()

list_groups(string  $search = null, int  $mode) : array

List all active contact groups of this source

Parameters

string $search

Optional search string to match group name

int $mode

Matching mode. Sum of rcube_addressbook::SEARCH_*

Returns

array —

Indexed list of contact groups, each a hash array

get_group()

get_group(string  $group_id) : array

Get group properties such as name and email address(es)

Parameters

string $group_id

Group identifier

Returns

array —

Group properties as hash array

create_group()

create_group(string  $group_name) : mixed

Create a contact group with the given name

Parameters

string $group_name

The group name

Returns

mixed —

False on error, array with record props in success

delete_group()

delete_group(string  $group_id) : bool

Delete the given group and all linked group members

Parameters

string $group_id

Group identifier

Returns

bool —

True on success, false if no data was changed

rename_group()

rename_group(string  $group_id, string  $new_name, string  $new_gid) : bool

Rename a specific contact group

Parameters

string $group_id

Group identifier

string $new_name

New name to set for this group

string $new_gid

New group identifier (if changed, otherwise don't set)

Returns

bool —

New name on success, false if no data was changed

add_to_group()

add_to_group(string  $group_id, array|string  $contact_ids) : int

Add the given contact records the a certain group

Parameters

string $group_id

Group identifier

array|string $contact_ids

List of contact identifiers to be added

Returns

int —

Number of contacts added

remove_from_group()

remove_from_group(string  $group_id, array|string  $contact_ids) : int

Remove the given contact records from a certain group

Parameters

string $group_id

Group identifier

array|string $contact_ids

List of contact identifiers to be removed

Returns

int —

Number of deleted group members

get_record_groups()

get_record_groups(mixed  $contact_id) : array

Get group assignments of a specific contact record

Parameters

mixed $contact_id

Record identifier

Returns

array —

List of assigned groups as ID=>Name pairs

get_col_values()

get_col_values(string  $col, array  $data, bool  $flat = false) : array

Utility function to return all values of a certain data column either as flat list or grouped by subtype

Parameters

string $col

Col name

array $data

Record data array as used for saving

bool $flat

True to return one array with all values, False for hash array with values grouped by type

Returns

array —

List of column values

compose_display_name()

compose_display_name(array  $contact, bool  $full_email = false) : string

Compose a valid display name from the given structured contact data

Parameters

array $contact

Hash array with contact data as key-value pairs

bool $full_email

Don't attempt to extract components from the email address

Returns

string —

Display name

compose_list_name()

compose_list_name(array  $contact) : string

Compose the name to display in the contacts list for the given contact record.

This respects the settings parameter how to list contacts.

Parameters

array $contact

Hash array with contact data as key-value pairs

Returns

string —

List name

compose_search_name()

compose_search_name(array  $contact, string  $email = null, string  $name = null, string  $templ = null) : string

Build contact display name for autocomplete listing

Parameters

array $contact

Hash array with contact data as key-value pairs

string $email

Optional email address

string $name

Optional name (self::compose_list_name() result)

string $templ

Optional template to use (defaults to the 'contact_search_name' config option)

Returns

string —

Display name

compose_contact_key()

compose_contact_key(array  $contact, string  $sort_col) : string

Create a unique key for sorting contacts

Parameters

array $contact

Contact record

string $sort_col

Sorting column name

Returns

string —

Unique key

__construct()

__construct(array  $p, bool  $debug = false, string  $mail_domain = null) : mixed

Object constructor

Parameters

array $p

LDAP connection properties

bool $debug

Enables debug mode

string $mail_domain

Current user mail domain name

Returns

mixed —

list_group_members()

list_group_members(string  $dn, bool  $count = false, array  $entries = null) : array

Get all members of the given group

Parameters

string $dn

Group DN

bool $count

Count only

array $entries

Group entries (if called recursively)

Returns

array —

Accumulated group members

_entry_sort_cmp()

_entry_sort_cmp(mixed  $a, mixed  $b) : mixed

Callback for sorting entries

Parameters

mixed $a
mixed $b

Returns

mixed —

set_debug()

set_debug(bool  $dbg = true) : mixed

Activate/deactivate debug mode

Parameters

bool $dbg

True if LDAP commands should be logged

Returns

mixed —

dn_encode()

dn_encode(string  $str) : string

HTML-safe DN string encoding

Parameters

string $str

DN string

Returns

string —

Encoded HTML identifier string

dn_decode()

dn_decode(string  $str) : string

Decodes DN string encoded with _dn_encode()

Parameters

string $str

Encoded HTML identifier string

Returns

string —

DN string

set_error()

set_error(int  $type, string  $message) : mixed

Setter for errors for internal use

Parameters

int $type

Error type (one of this class' error constants)

string $message

Error message (name of a text label)

Returns

mixed —

compare_search_value()

compare_search_value(string  $colname, string|array  $value, string  $search, int  $mode) : bool

Compare search value with contact data

Parameters

string $colname

Data name

string|array $value

Data value

string $search

Search value

int $mode

Search mode

Returns

bool —

Comparison result

extended_search()

extended_search(bool  $count = false) : int|array

Wrapper on LDAP searches with group_filters support, which allows searching for contacts AND groups.

Parameters

bool $count

Return count instead of the records

Returns

int|array —

Count of records or the result array (with 'count' item)

add_autovalues()

add_autovalues(array  $attrs) : mixed

Generate missing attributes as configured

Parameters

array $attrs

LDAP record attributes

Returns

mixed —

_connect()

_connect() : mixed

Establish a connection to the LDAP server

Returns

mixed —

_list_group_members()

_list_group_members(string  $dn, array  $entry, string  $attr, bool  $count) : array

Fetch members of the given group entry from server

Parameters

string $dn

Group DN

array $entry

Group entry

string $attr

Member attribute to use

bool $count

Count only

Returns

array —

Accumulated group members

_list_group_memberurl()

_list_group_memberurl(string  $dn, array  $entry, bool  $count) : array

List members of group class groupOfUrls

Parameters

string $dn

Group DN

array $entry

Group entry

bool $count

True if only used for counting

Returns

array —

Accumulated group members

_ldap2result()

_ldap2result(mixed  $rec) : mixed

Converts LDAP entry into an array

Parameters

mixed $rec

Returns

mixed —

_map_field()

_map_field(mixed  $field) : mixed

Return LDAP attribute(s) for the given field

Parameters

mixed $field

Returns

mixed —

_map_data()

_map_data(mixed  $save_cols) : mixed

Convert a record data set into LDAP field attributes

Parameters

mixed $save_cols

Returns

mixed —

_attr_name()

_attr_name(mixed  $namev) : mixed

Returns unified attribute name (resolving aliases)

Parameters

mixed $namev

Returns

mixed —

is_group_entry()

is_group_entry(mixed  $entry) : mixed

Determines whether the given LDAP entry is a group record

Parameters

mixed $entry

Returns

mixed —

_fetch_groups()

_fetch_groups(mixed  $search = null, mixed  $mode, mixed  $vlv_page = null) : mixed

Fetch groups from server

Parameters

mixed $search
mixed $mode
mixed $vlv_page

Returns

mixed —

get_group_entry()

get_group_entry(mixed  $group_id) : mixed

Fetch a group entry from LDAP and save in local cache

Parameters

mixed $group_id

Returns

mixed —

get_group_member_attr()

get_group_member_attr(mixed  $object_classes = [], mixed  $default = 'member') : mixed

Detects group member attribute name

Parameters

mixed $object_classes
mixed $default

Returns

mixed —